---
title: Getting Started
description: How to install and set up Chakra UI in your project
---

## Installation

Inside your React project directory, install Chakra UI by running either of the
following:

```bash
npm i @chakra-ui/react @emotion/react@^11 @emotion/styled@^11 framer-motion@^4
```

```bash
yarn add @chakra-ui/react @emotion/react@^11 @emotion/styled@^11 framer-motion@^4
```

> For `create-react-app` installation instructions, check this
> [CRA templates guide](/guides/integrations/with-cra).

## Set up Provider

For Chakra UI to work correctly, you need to set up the `ChakraProvider` at the
root of your application.

Go to the root of your application and do this:

```jsx live=false
import * as React from "react"

// 1. import `ChakraProvider` component
import { ChakraProvider } from "@chakra-ui/react"

function App({ Component }) {
  // 2. Use at the root of your app
  return (
    <ChakraProvider>
      <Component />
    </ChakraProvider>
  )
}
```

> - For Create React App, you need to set this up in `index.js` or `index.tsx`

### Next.js
<Box mt={3}>
  <AspectRatio ratio={16 / 8.84}>
    <VideoPlayer
      width="100%"
      height="100%"
      url="https://www.youtube.com/watch?v=wI2vqXsjsIo"
      config={{
        youtube: {
          playerVars: {
            controls: true
          }
        }
      }}
    />
  </AspectRatio>
</Box>

Go to `pages/_app.js` or `pages/_app.tsx` (create if it doesn't exist) and add
this:

```jsx live=false
import { ChakraProvider } from "@chakra-ui/react"

function MyApp({ Component, pageProps }) {
  return (
    <ChakraProvider>
      <Component {...pageProps} />
    </ChakraProvider>
  )
}

export default MyApp
```

### Gatsby

Add the
[@chakra-ui/gatsby-plugin](https://www.gatsbyjs.com/plugins/@chakra-ui/gatsby-plugin/). It
does everything automatically for you!

```bash
npm i @chakra-ui/gatsby-plugin
```

```bash
yarn add @chakra-ui/gatsby-plugin
```

Then add the plugin to your `gatsby-config`.

```js
// gatsby-config.js

module.exports = {
  plugins: ["@chakra-ui/gatsby-plugin"],
}
```

## Add custom theme (Optional)

If you need to customize the default chakra theme to match your design
requirements, you can extend the `theme` from `@chakra-ui/react`.

Chakra UI provides an `extendTheme` function that deep merges the default theme
with your customizations.

```jsx live=false
// 1. Import the extendTheme function
import { extendTheme } from "@chakra-ui/react"

// 2. Extend the theme to include custom colors, fonts, etc
const colors = {
  brand: {
    900: "#1a365d",
    800: "#153e75",
    700: "#2a69ac",
  },
}

const theme = extendTheme({ colors })

// 3. Pass the `theme` prop to the `ChakraProvider`
function App({ Component }) {
  return (
    <ChakraProvider theme={theme}>
      <Component />
    </ChakraProvider>
  )
}
```

### ChakraProvider Props

| Name             | Type             | Default               | Description                                         |
| ---------------- | ---------------- | --------------------- | --------------------------------------------------- |
| resetCSS         | `boolean`        | `true`                | automatically includes `<CSSReset />`               |
| theme            | `Theme`          | `@chakra-ui/theme`    | optional custom theme                               |
| colorModeManager | `StorageManager` | `localStorageManager` | manager to persist a users color mode preference in |
| portalZIndex     | `number`         | `undefined`           | common z-index to use for `Portal`                  |

That's it, you're good to go!

## Optional Packages

- Icons: If you want to use the icons from Chakra UI, install `@chakra-ui/icons`
- Theme Tools: If you intend to customize components or build your own design
  system, this package includes useful utilities. Install
  `@chakra-ui/theme-tools`.

## Notes on TypeScript 🚨

Please note that when adding Chakra UI to a TypeScript project, a minimum
TypeScript version of `4.1.0` is required.

If you're adding Chakra UI to a `create-react-app` project, this means you'll
need to manually upgrade `typescript` to `^4.1.0`.

See [the guide for our create-react-app](/guides/integrations/with-cra)
templates if you'd like to generate a Chakra-enabled `create-react-app` project
from scratch.

## Contributing

Please see our [contribution guidelines](/docs/contributing) to learn how you
can contribute to this project.
